ATSUSetLayoutControls

OSStatus ATSUSetLayoutControls (
                     ATSUTextLayout iTextLayout,
                     ItemCount iAttributeCount,
                     ATSUAttributeTag iTag[],
                     ByteCount iValueSize[],
                     ATSUAttributeValuePtr iValue[]);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to a text layout object whose attributes you want to set. You cannot pass NULL for this parameter.

iAttributeCount

The number of text layout attributes you want to set. This value should correspond to the number of elements in the iTag and iValueSize arrays.

iTag

An array of values of type ATSUAttributeTag. Each element in the array must contain a valid tag that corresponds to the text layout attribute value you wish to set. See Text Layout Attribute Tag Constants for a description of the Apple-defined text layout attribute tag constants. If you pass a style run attribute tag constant or an ATSUI-reserved tag constant in this parameter, ATSUSetLayoutControls returns the result code kATSUInvalidAttributeTagErr. You cannot pass NULL for this parameter.

iValueSize

An array of values of type ByteCount. Each element in the array must contain the size (in bytes) of the corresponding text layout attribute value being set. If you pass a size that is less than required, ATSUSetLayoutControls returns the result code kATSUInvalidAttributeSizeErr, and the function sets no attributes. If, after having checked all the given sizes and found them acceptable, ATSUSetLayoutControls sets text layout attributes. You cannot pass NULL for this parameter.

iValue

An array of pointers of type ATSUAttributeValuePtr. Each pointer in the array must reference a valid value and correspond to a tag in the iTag array. If you pass an invalid or undefined value, ATSUSetLayoutControls returns the result code kATSUInvalidAttributeValueErr. You cannot pass NULL for this parameter.

function result

A result code. See Result Codes. If there is a function error, ATSUSetAttributes will not set any style run attributes.

DISCUSSION

The ATSUSetLayoutControls function sets one or more text layout attribute value(s) for an entire text layout object. If you wish to set the text layout attribute values of a single line in a text layout object, see the function ATSUSetLineControls. Note that when you set a text layout attribute value for a line, this value will override the value of the text layout attribute set for the text layout object containing the line. This is true even if the attributes for the line are set before those of the entire text layout object containing the line.

SPECIAL CONSIDERATIONS

ATSUSetLayoutControls may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.